HyperLib 1997 Winter

home *** CD-ROM | disk | FTP | other *** search

/ HyperLib 1997 Winter - Disc 1 / HYPERLIB-1997-Winter-CD1.ISO.7z / HYPERLIB-1997-Winter-CD1.ISO / オンラインウェア / PRG / FileDropper2.0ｧ1 Folder.sit / FileDropper2.0ﾟ1 Folder / Read Me - File Dropper < prev next >

Wrap

Text File | 1996-06-04 | 14KB | 300 lines

File Dropper 2.0ｧ1 Written by Troy Anderson Copyright ｩ 1996, Troy Anderson; All Rights Reserved What Is This Thing? File Dropper is a CodeWarrior library that implements an application that you can drop files or folders onto to do batch operations on. It handles the getting of the AppleEvents, the main event loop, and the menus. You need only write the code that acts on the individual files. It is WorkWare - I truely believe that if you use this to implement a file handling utility, you will save time - probably on the order of days, all things considered. I ask that you send me one hour's pay, or US$50 (whichever is greater :) if you use this library and it saves you time. My address is: I sincerely appreciate it. US Mail: Troy Anderson Concrete Software, Inc. 8777 N Gainey Center Drive Suite 236 Scottsdale, AZ 85258 New Features in 2.0ｧ1 ･ Updated the code to CodeWarrior and to support both 68K and PPC native applications. ･ﾊAdded CW project stationery so creating new File Dropper based application is painless. ･ Removed support for pre-System 7 computers - sorry. New Features in 1.1ｧ4 ･ﾊChanged the "legal" mumbo-jumbo. New Features in 1.1ｧ3 ･ Fixed a bug so that when you drop a folder onto your File Dropper application, all the files inside are processed in stead of just the first one. New Features in 1.1ｧ2 ･ﾊBuilt "File Dropper ｹ" in THINK C 6.0 ･ﾊThe cursor is NOT reset to an arrow after each call to SetStatusPercentage. ･ﾊIf you return FALSE from the eStartup, eSFInitialize, or eAEInitialize messages, File Dropper will send you an eQuitting message and quit the application. ･ﾊIf you return FALSE from the eValidate message, File Dropper will skip any remaining files in the current batch. ･ﾊIf you return FALSE from an eDispose message, File Dropper will send you an eQuitting message and quit the application. Returning TRUE from an eDispose message will cause File Dropper to continue running. This behavior does NOT depend upon which of eSFInitialize or eAEInitialize was sent to you. ･ﾊIf you return TRUE from an eQuitting message, the File Dropper quits. On the other hand, if you return FALSE from an eQuitting message, File Dropper will quit. ･ﾊIf you want the source code to File Dropper, send me money (see the end of this document). ･ﾊAdded an eUserCancelled message for when the user clicks Cancel in the status box. ･ Added an eIdle message. ･ﾊAdded the ChangeStatusMessage function that lets you change the message in the status dialog on the fly, during your processing of the file. ･ﾊChanged some things internally, so you can NOT call InstallCustomGetFSSpecFunc, InstallCustomFileFilterFunc, or InstallCustomDialogHookFunc from an eSFInitialize or eAEInitialize message any more, just from eStartup. ･ﾊFixed a bug in the ErrorAlert function so that text relating to the error as well as the word "Error." show up in the dialog. ･ﾊMade it simpler to support AboutBox functionality. You just put text in STR# resource 129, and it will be displayed in the warp stars. To enable this feature, return TRUE from the eDoAboutBox message. New Features in 1.1ｧ1 ･ Now you can specify if you want the status dialog displayed while you are working on the files, wether they were selected with SFGetFile or an AppleEvent. ･ There is a progress bar like Finder 7's that you update by specifying how far along you are with a percentage (0 - 100). You can elect to turn this option off, too. How Do I Implement My Part? All definitions and prototypes that you need are in the "FD Interface.h" file. You simply write the ModuleMain function, and let the library do the rest. The ModuleMain function takes two parameters, a short and a ModuleDataRec. The short is a message that tells you why you were called. The ModuleDataRec is a record that contains data that you may need in order to perform the required task. It returns a Boolean value. The returned value is ignored in all but one case, when you are sent an eValidateFile message. See the eValidateFile message description below for details. Be sure that your project includes the "File Dropper Required Resources" file as well as any resource file you need. To allow dropping of different types of files/folders/volumes onto your application, change the 'FREF' resource to include the types of files you can act on. There are some special types that correspond to folders, volumes, etc. For a more indepth discussion of this, see section 9-17 of Inside Macintosh Volume VI. See section 9-30 for a list of file types you can use for folders, floppy disks, the trash, etc. Be sure to change the creator type in the Preferences:68K Project or Preferences:PPC Project panels, and the creator type in the resource file, and to give your application a cool icon. What Is A ModuleDataRec? The ModuleDataRec is defined as follows: typedef struct { FSSpec *theFile; // a file specification long refcon; // a reference constant for you to do with what you will } ModuleDataRec; What Are The Messages? There are 6 possible messages, they are eStartup, eAEInitialize, eSFInitialize, eValidateFile, eProcessFile, eDispose, and eQuitting. You get the messages in this order: eStartup This tells you that the program just started up. You get this message exactly once. In the ModuleDataRec, theFile and refcon are initialize to NULL and 0 respectively. You are free to use refcon for anything you choose, including allocating a handle and saving its value in refcon so you can have additional storage. Nothing really precludes you from having global data hanging around, but someday this thing may evolve into a CODE resource interface that will make having globals more difficult. I never touch refcon, so what you do with it is up to you. This is a where you should call the customization routines like SetStatusParams, InstallCustomGetFSSpecFunc, InstallCustomFileFilterFunc, or InstallCustomDialogHookFunc. Although it's all right to call SetStatusParams from eAEInitialize or eSFInitialize as well. Return TRUE if everything you did turned out OK (e.g. you got all the memory you asked for). Returning FALSE causes File Dropper to send you an eQuitting message and quit. eAEInitialize or eSFInitialize This tells you that a file/folder/volume has been selected by the user to be acted upon. eAEInitialize indicates that the file/folder/volume was "dropped" onto the application or sent to it using an 'odoc' AppleEvent. eSFInitialize indicates that the file (of folder or volume if you've installed a Custom GetFSSpec Function using InstallCustomGetFSSpecFunction()) was selected by the user using a standard get file dialog. NOTE: You get this message AFTER the user selects the file. If you want to install a custom get file using InstallCustomGetFSSpecFunc, InstallCustomFileFilterFunc, or InstallCustomDialogHookFunc, do it in eStartup, not here. It is handy to know wether the file was obtained from a "drop" or from a GetFile dialog if, for instance, you have options based on keys pressed when "dropped," but not when obtained from a dialog. You will receive one of these messages for each batch of files to be processed, before you are told to do any processing. In ModuleDataRec, theFile is meaningless during this message. Return TRUE if everything you did as a result of this message was OK. Returning FALSE causes File Dropper to send you an eQuitting message and quit. eValidateFile This asks you if the file specified in the theFile parameter of the ModuleDataRec record is valid for you to work on. I.E. should eProcessFile be sent? Return TRUE if you want to process it, otherwise return FALSE. eProcessFile This tells you to do your thing. You get this message for each file in the batch. The ModuleDataRec will contain a pointer to the FSSpec for the file that you are to process in the theFile parameter. If you return TRUE and there are any more files to process, you will be sent the next file in the batch. If you return FALSE, no more files will be sent to you for the current batch. eUserCancelled This tells you that the user clicked Cancel in the status dialog while a file was being processed. The ModuleDataRec will contain a pointer to the FSSpec for the file that was being processed in the theFile parameter. Since File Dropper handles the status dialog only when you call SetStatusPercentage, you will get this message while in a call to SetStatusPercentage, thus your ModuleMain must be reentrant with respect to the eUserCancelled case. If you return TRUE, you will get an eDispose message, followed by an eQuitting message, then File Dropper will ExitToShell. Returning FALSE causes File Dropper to act as if the Cancel button was not pressed. I suggest you always return TRUE unless you have a really good reason not to, like you are keeping track of the fact that the user cancelled and will return FALSE from the next eProcessFile. eDispose This tells you that the batch is finished. This balances out the eAEInitialize or eSFInitialize messages. It gives you a chance to clean up any data structures you set up there. Return FALSE if you want File Dropper to send you an eQuitting message and quit. Return TRUE if you want File Dropper to keep running. In ModuleDataRec, theFile is meaningless. eQuitting This tells you that the application is about to quit. If you need to save or flush anything, this is the time to do it. The return value is ignored for this call. In ModuleDataRec, theFile is meaningless. eIdle You get one of these for each NULL event File Dropper gets. You won't get one while you're processing a file. eDoAboutBox If you return TRUE from this message, I will handle the about box by reading from the STR# number 129. I will read all strings starting with number 1 in that resource and display them in the about box. Only up to about 6 strings will actually fit in the about box. If you return FALSE from the eDoAboutBox message, I will assume that you handled the about box and do nothing. In summary: eStartup REPEAT AS LONG AS USER SELECTS THINGS FROM THE GET FILE DIALOG eSFInitialize REPEAT FOR EACH FILE eValidateFile eProcessFile (if validation succeeded) END REPEAT eDispose eIdle (until the user selects Open, Quit, or more files get dropped on) END REPEAT* eQuitting * You can make it so that File Dropper quits after the first selection/processing of a file. See the section on eDispose. -OR- eStartup eAEInitialize REPEAT FOR EACH FILE eValidateFile eProcessFile (if validation succeeded) END REPEAT eDispose eIdle (until the user selects Open, Quit, or more files get dropped on) eQuitting You can make it so that File Dropper stays open until the user actually selects Quit from the File menu or a 'quit' AppleEvent comes in. See the section on eDispose. About The Guy Who Wrote It This was written by me, Troy Anderson, after a comment from a user of Marker that wanted source so he could do something else with the files that were dropped on the application. This allows you to create little utility applications that do fun things. If you really like this, and you write software, send me a copy of it. Thanks. Internet: troy@concrete.com America Online: Troy A1 Compuserve: 70410,1407 US Mail: Troy Anderson 8777 N Gainey Center Drive Suite 236 Scottsdale, AZ 85258 I Want The Source Code! If you want the source code (10 commented source files) including AppleEvent sending and receiving, handling, file manipulation, PowerPC vs. 68K coding, finder-like status bar, and the warp stars about box effect, send me a U.S. check for $100 and a self addressed envelope that will hold a disk or your Compuserve or America Online address or send $90 and your internet address and I'll send you the latest version of the source code including at least everything mentioned in this exceedingly long sentence. See paragraph three in the Legal Stuff section for what you can do once you have the souce code, besides reading it. Legal Stuff If you like it, let me know. If you use it, send me money - please. If there are bugs, tell me, I may actually fix them. Every effort has been made to ensure that this software works as specified, but it has no warranties, expressed or implied, as to its usefulness, stability, or functionalty. Use this software at your own risk. You may use applications made with a registered File Dropper for your personal use at no additional charge, but for commercial use, you must aquire a site license from me. Contact me at one of the above addresses to find out about the site licenses. Anyone wishing to distribute an application using File Dropper along with any commercial or shareware software package, or as a commercial or shareware application, in house or out, may do so only with my expressed written consent. If you receive the source code to File Dropper, you may modify it and use it in your own projects and distribute them as long as they are free of any charge, my name is displayed in the About Box or other equally accessable place, and are used for only non-commercial use. If the application you are distributing is a File Dropper type application, you must either leave the "About YourAppName..." menu item and functionality in place, although you can change the menu item's name to be more appropriate, or give me credit in your custom about box, including "This application is based on File Dropper by Troy Anderson" and "File Dropper ｩﾊ1996 Troy Anderson".